// Copyright (c) Microsoft Corporation 
// All rights reserved

namespace Microsoft.Windows.Controls.Specialized.TextModel
{
    using System;

    /// <summary>
    /// Describes the contract for Text Buffer implementations.
    /// </summary>
    public interface ITextBuffer : ITextReader, IUserData
    {
        /// <summary>
        /// Gets the starting character index of the specified line
        /// </summary>
        /// <param name="line">
        /// The line number whose starting character index is required
        /// </param>
        int GetStartOfLine(int line);

        /// <summary>
        /// Gets the length of the specified line (not including the line break characters)
        /// </summary>
        /// <param name="line">
        /// The line number whose length is required
        /// </param>
        int GetLengthOfLine(int line);

        /// <summary>
        /// Gets the position of the first character in the line containing the character at the specified 
        /// position
        /// </summary>
        int GetStartOfLineContaining(int position);

        /// <summary>
        /// Gets the position of the last character in the line containing the character at the specified 
        /// position
        /// </summary>
        int GetEndOfLineContaining(int position);

        /// <summary>
        /// Gets the position of the first character in the line next to the one containing the character
        /// at the specified position
        /// </summary>
        int GetStartOfNextLine(int position);

        /// <summary>
        /// Gets the position of the first character in the line previous to the one containing the character
        /// at the specified position
        /// </summary>
        int GetStartOfPreviousLine(int position);

        /// <summary>
        /// Gets the line number that contains the character at the specified position
        /// </summary>
        int GetLineContaining(int position);

        /// <summary>
        /// Gets the line offset given the absolute position
        /// </summary>
        int GetColumnOffset(int position);

        /// <summary>
        /// Gets the TextLine given the line number
        /// </summary>
        BufferLine GetTextLine(int lineNumber);

        /// <summary>
        /// Inserts the given text in the specified position
        /// </summary>
        /// <param name="position">
        /// The point of insertion of text
        /// </param>
        /// <param name="text">
        /// The text to insert
        /// </param>
        void Insert(int position, string text);

        /// <summary>
        /// Deletes the specified number of characters from the given start position
        /// </summary>
        /// <param name="startPosition">
        /// The position to start deleting characters from
        /// </param>
        /// <param name="charsToDelete">
        /// The number of characters to delete
        /// </param>
        void Delete(int startPosition, int charsToDelete);

        /// <summary>
        /// Replaces the specified range of characters with the new text.
        /// </summary>
        /// <param name="startPosition">
        /// The starting position of the range of characters to replace
        /// </param>
        /// <param name="charsToReplace">
        /// The number of characters to replace
        /// </param>
        /// <param name="replaceWith">
        /// The new text that replaces the specified range
        /// </param>
        void Replace(int startPosition, int charsToReplace, string replaceWith);

        /// <summary>
        /// Creates an ITextEdit object that can handle compounds edits on this buffer
        /// </summary>
        ITextEdit CreateEdit();

        /// <summary>
        /// Freezes the text buffer 
        /// </summary>
        /// <param name="version"></param>
        /// <returns></returns>
        ITextReader Freeze(ITextVersion version);

        /// <summary>
        /// Indicates whether version belongs to this buffer
        /// </summary>
        bool VersionBelongsToBuffer(ITextVersion version);

        /// <summary>
        /// Compute length of particular version of this buffer.
        /// </summary>
        /// <param name="version">The version of interest; throws ArgumentException
        /// if !VersionBelongsToBuffer(version)</param>
        int GetLengthOfVersion(ITextVersion version);

        /// <summary>
        /// A buffer changed notification event
        /// </summary>
        event TextChangedEventHandler Changed;

        /// <summary>
        /// Gets the Type of the document that the text in this text buffer represents
        /// </summary>
        new string DocumentType
        {
            get;
            set;
        }
    }
}
